home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 2.iso / dist / fw_groff.idb / usr / freeware / info / groff-4.z / groff-4
Text File  |  2002-04-08  |  52KB  |  1,431 lines
  1. This is groff, produced by makeinfo version 4.0 from groff.texinfo.
  2.  
  3. INFO-DIR-SECTION Miscellaneous
  4. START-INFO-DIR-ENTRY
  5. * Groff: (groff).  The GNU troff document formatting system.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This Info file documents GNU troff version 1.16.
  9.  
  10.    Published by the Free Software Foundation 59 Temple Place, Suite 330
  11. Boston, MA  02111-1307  USA
  12.  
  13.    Copyright (C) 1994-2000 Free Software Foundation, Inc.
  14.  
  15.    Permission is granted to make and distribute verbatim copies of this
  16. manual provided the copyright notice and this permission notice are
  17. preserved on all copies.
  18.  
  19.    Permission is granted to copy and distribute modified versions of
  20. this manual under the conditions for verbatim copying, provided that the
  21. entire resulting derived work is distributed under the terms of a
  22. permission notice identical to this one.
  23.  
  24.    Permission is granted to copy and distribute translations of this
  25. manual into another language, under the above conditions for modified
  26. versions, except that this permission notice may be stated in a
  27. translation approved by the Foundation.
  28.  
  29.    Permission is granted to copy and distribute modified versions of
  30. this manual under the conditions for verbatim copying, provided also
  31. that the section entitled "GNU General Public License" is included
  32. exactly as in the original, and provided that the entire resulting
  33. derived work is distributed under the terms of a permission notice
  34. identical to this one.
  35.  
  36.    Permission is granted to copy and distribute translations of this
  37. manual into another language, under the above conditions for modified
  38. versions, except that the section entitled "GNU General Public License"
  39. may be included in a translation approved by the Free Software
  40. Foundation instead of in the original English.
  41.  
  42. 
  43. File: groff,  Node: Page Layout,  Next: Page Control,  Prev: Line Layout,  Up: gtroff Reference
  44.  
  45. Page Layout
  46. ===========
  47.  
  48.    `gtroff' provides some very primitive operations for controlling
  49. page layout.
  50.  
  51.  - Request: .pl [length]
  52.  - Request: .pl +length
  53.  - Request: .pl -length
  54.  - Register: \n[.p]
  55.      Set the "page length" to LENGTH (or increment or decrement the
  56.      current value by LENGTH).  This is the length of the physical
  57.      output page.  The default scaling indicator is `v'.
  58.  
  59.      The current setting can be found in the read-only number register
  60.      `.p'.
  61.  
  62.      Note that this only specifies the size of the page, not the top and
  63.      bottom margins.  Those are not set by `gtroff' directly.  *Note
  64.      Traps::, for further information on how to do this.
  65.  
  66.      Negative `pl' values are possible also, but not very useful: No
  67.      trap is sprung, and each line is output on a single page (thus
  68.      suppressing all vertical spacing).
  69.  
  70.      If no argument or an invalid argument is given, `pl' sets the page
  71.      length to 11i.
  72.  
  73.    `gtroff' provides several operations which help in setting up top
  74. and bottom titles (or headers and footers).
  75.  
  76.  - Request: .tl 'left'center'right'
  77.      Print a "title line".  It consists of three parts: a left
  78.      justified portion, a centered portion, and a right justified
  79.      portion.  The argument separator `'' can be replaced with any
  80.      character not occurring in the title line.  The `%' character is
  81.      replaced with the current page number.  This character can be
  82.      changed with the `pc' request (see below).
  83.  
  84.      Without argument, `tl' is ignored.
  85.  
  86.      Some notes:
  87.  
  88.         * A title line is not restricted to the top or bottom of a page.
  89.  
  90.         * `tl' prints the title line immediately, ignoring a partially
  91.           filled line (which stays untouched).
  92.  
  93.         * It is not an error to omit closing delimiters.  For example,
  94.           `.tl /foo' is equivalent to `.tl /foo///': It prints a title
  95.           line with the left justified word `foo'; the centered and
  96.           right justfied parts are empty.
  97.  
  98.         * Any modifications to the current environment within `tl' (e.g.
  99.           changing the font or font size) are undone after processing
  100.           `tl'.
  101.  
  102.         * `tl' accepts the same parameter delimiting characters as the
  103.           `\A' escape; see *Note Escapes::.
  104.  
  105.  - Request: .lt [length]
  106.  - Request: .lt +length
  107.  - Request: .lt -length
  108.  - Register: \n[.lt]
  109.      The title line is printed using its own line length, which is
  110.      specified (or incremented or decremented) with the `lt' request.
  111.      Initially, the title line length is set to 6.5i.  If a negative
  112.      line length is specified (which is not allowed), `gtroff' emits a
  113.      warning of type `range' and sets the title line length to zero.
  114.      The default scaling indicator is `m'.  If `lt' is called without
  115.      an argument, the title length is reset to the previous value
  116.      before the last call to `lt'.
  117.  
  118.      The current setting of this is available in the `.lt' read-only
  119.      number register; it is associated with the current environment
  120.      (*note Environments::).
  121.  
  122.  
  123.  - Request: .pn page
  124.  - Request: .pn +page
  125.  - Request: .pn -page
  126.  - Register: \n[.pn]
  127.      Change (increase or decrease) the page number of the _next_ page.
  128.      The only argument is the page number; the request is ignored
  129.      without a parameter.
  130.  
  131.      The read-only number register `.pn' contains the number of the next
  132.      page: either the value set by a `pn' request, or the number of the
  133.      current page plus 1.
  134.  
  135.  - Register: \n[%]
  136.      A read-write register holding the current page number.
  137.  
  138.  - Request: .pc [char]
  139.      Change the page number character (used by the `tl' request) to a
  140.      different character.  With no argument, this mechanism is disabled.
  141.      Note that this doesn't affect the number register `%'.
  142.  
  143.    *Note Traps::.
  144.  
  145. 
  146. File: groff,  Node: Page Control,  Next: Fonts,  Prev: Page Layout,  Up: gtroff Reference
  147.  
  148. Page Control
  149. ============
  150.  
  151.  - Request: .bp [page]
  152.  - Request: .bp +page
  153.  - Request: .bp -page
  154.      Stop processing the current page and move to the next page.  This
  155.      request causes a break.  It can also take an argument to set
  156.      (increase, decrease) the page number of the next page.  The only
  157.      difference between `bp' and `pn' is that `pn' does not cause a
  158.      break or actually eject a page.
  159.  
  160.  
  161.           .de newpage                         \" define macro
  162.           'bp                                 \" begin page
  163.           'sp .5i                             \" vertical space
  164.           .tl 'left top'center top'right top' \" title
  165.           'sp .3i                             \" vertical space
  166.           ..                                  \" end macro
  167.  
  168.      `bp' has no effect if not called within the top-level diversion
  169.      (*note Diversions::).
  170.  
  171.  - Request: .ne [space]
  172.      It is often necessary to force a certain amount of space before a
  173.      new page occurs.  This is most useful to make sure that there is
  174.      not a single "orphan" line left at the bottom of a page.  The `ne'
  175.      request ensures that there is a certain distance, specified by the
  176.      first argument, before the next page is triggered (see *Note
  177.      Traps::, for further information).  The default unit for `ne' is
  178.      `v'; the default value of SPACE is 1v if no argument is given.
  179.  
  180.      For example, to make sure that no fewer than 2 lines get orphaned,
  181.      do the following before each paragraph:
  182.  
  183.  
  184.           .ne 2
  185.           text text text
  186.  
  187.  
  188.  - Request: .sv [space]
  189.      `sv' is similar to the `ne' request; it reserves the specified
  190.      amount of vertical space.  If the desired amount of space exists
  191.      before the next trap (bottom page boundary), the space is output
  192.      immediately (ignoring a partial filled line which stays
  193.      untouched).  If there is not enough space, it is stored for later
  194.      output via the `os' request.  The default value is 1v if no
  195.      argument is given; the default unit is `v'.
  196.  
  197. 
  198. File: groff,  Node: Fonts,  Next: Sizes,  Prev: Page Control,  Up: gtroff Reference
  199.  
  200. Fonts
  201. =====
  202.  
  203.    `gtroff' can switch fonts at any point in the text.
  204.  
  205.    The basic set of fonts is `R', `I', `B', and `BI'.  These are Times
  206. Roman, Italic, Bold, and Bold Italic.  For non-tty devices, there is
  207. also at least one symbol font which contains various special symbols
  208. (Greek, mathematics).
  209.  
  210. * Menu:
  211.  
  212. * Changing Fonts::
  213. * Font Families::
  214. * Font Positions::
  215. * Using Symbols::
  216. * Special Fonts::
  217. * Artificial Fonts::
  218. * Ligatures and Kerning::
  219.  
  220. 
  221. File: groff,  Node: Changing Fonts,  Next: Font Families,  Prev: Fonts,  Up: Fonts
  222.  
  223. Changing Fonts
  224. --------------
  225.  
  226.  - Request: .ft [font]
  227.  - Escape: \fF
  228.  - Escape: \f(FN
  229.  - Escape: \f[FONT]
  230.      The `ft' request and the `\f' escape change the current font to
  231.      FONT (one-character name F, two-character name FN).
  232.  
  233.      If FONT is a style name (as set with the `sty' request or with the
  234.      `styles' command in the `DESC' file), use it within the current
  235.      font family (as set with the `fam' request or with the `family'
  236.      command in the `DESC' file).
  237.  
  238.      With no argument or using `P' as an argument, `.ft' switches to
  239.      the previous font.  Use `\fP' or `\f[P]' to do this with the
  240.      escape.
  241.  
  242.      Fonts are generally specified as upper-case strings, which are
  243.      usually 1 to 4 characters representing an abbreviation or acronym
  244.      of the font name.  This is no limitation, just a convention.
  245.  
  246.      The example below produces two identical lines.
  247.  
  248.  
  249.           eggs, bacon,
  250.           .ft B
  251.           spam
  252.           .ft
  253.           and sausage.
  254.           
  255.           eggs, bacon, \fBspam\fP and sausage.
  256.  
  257.      *Note Font Positions::, for an alternative syntax.
  258.  
  259.  - Request: .ftr f [g]
  260.      Translate font F to font G.  Whenever a font named F is referred
  261.      to in a `\f' escape sequence, or in the `ft', `ul', `bd', `cs',
  262.      `tkf', `special', `fspecial', `fp', or `code' requests, font G is
  263.      used.  If G is missing or equal to F the translation is undone.
  264.  
  265. 
  266. File: groff,  Node: Font Families,  Next: Font Positions,  Prev: Changing Fonts,  Up: Fonts
  267.  
  268. Font Families
  269. -------------
  270.  
  271.    Due to the variety of fonts available, `gtroff' has added the
  272. concept of "font families" and "font styles".  The fonts are specified
  273. as the concatenation of the font family and style.  Specifying a font
  274. without the family part causes `gtroff' to use that style of the
  275. current family.
  276.  
  277.    Currently, only POSTSCRIPT fonts are set up to this mechanism.  By
  278. default, `gtroff' uses the Times family with the four styles `R', `I',
  279. `B', and `BI'.
  280.  
  281.    This way, it is possible to use the basic four fonts and to select a
  282. different font family on the command line (*note Groff Options::).
  283.  
  284.  - Request: .fam [family]
  285.  - Register: \n[.fam]
  286.      Switch font family to FAMILY.  If no argument is given, switch
  287.      back to the previous font family.  The current font family is
  288.      available in the read-only number register `.fam' (this is a
  289.      string-valued register); it is associated with the current
  290.      environment.
  291.  
  292.  
  293.           spam,
  294.           .fam H    \" helvetica family
  295.           spam,     \" used font is family H + style R = HR
  296.           .ft B     \" family H + style B = font HB
  297.           spam,
  298.           .fam T    \" times family
  299.           spam,     \" used font is family T + style B = TB
  300.           .ft AR    \" font AR (not a style)
  301.           baked beans,
  302.           .ft R     \" family T + style R = font TR
  303.           and spam.
  304.  
  305.  
  306.  - Request: .sty n style
  307.      Associate STYLE with font position N.  A font position can be
  308.      associated either with a font or with a style.  The current font
  309.      is the index of a font position and so is also either a font or a
  310.      style.  When it is a style, the font that is actually used is the
  311.      font the name of which is the concatenation of the name of the
  312.      current family and the name of the current style.  For example, if
  313.      the current font is 1 and font position 1 is associated with
  314.      style `R' and the current font family is `T', then font `TR' will
  315.      be used.  If the current font is not a style, then the current
  316.      family is ignored.  When the requests `cs', `bd', `tkf', `uf', or
  317.      `fspecial' are applied to a style, then they will instead be
  318.      applied to the member of the current family corresponding to that
  319.      style.
  320.  
  321.      N must be a non-negative integer value.
  322.  
  323.      The default family can be set with the `-f' option (*note Groff
  324.      Options::).  The `styles' command in the `DESC' file controls
  325.      which font positions (if any) are initially associated with styles
  326.      rather than fonts.  For example, the default setting for
  327.      POSTSCRIPT fonts
  328.  
  329.  
  330.           styles R I B BI
  331.  
  332.      is equivalent to
  333.  
  334.  
  335.           .sty 1 R
  336.           .sty 2 I
  337.           .sty 3 B
  338.           .sty 4 BI
  339.  
  340.      `.fam' always checks whether the current font position is valid;
  341.      this can give surprising results if the current font position is
  342.      associated with a style.
  343.  
  344.      In the following example, we want to access the POSTSCRIPT font
  345.      `FooBar' from the font family `Foo':
  346.  
  347.  
  348.           .sty \n[.fp] Bar
  349.           .fam Foo
  350.               => warning: can't find font `FooR'
  351.  
  352.      The default font position at start-up is 1; for the POSTSCRIPT
  353.      device, this is associated with style `R', so `gtroff' tries to
  354.      open `FooR'.
  355.  
  356.      A solution to this problem is to use a dummy font like the
  357.      following:
  358.  
  359.  
  360.           .fp 0 dummy TR    \" set up dummy font at position 0
  361.           .sty \n[.fp] Bar  \" register style `Bar'
  362.           .ft 0             \" switch to font at position 0
  363.           .fam Foo          \" activate family `Foo'
  364.           .ft Bar           \" switch to font `FooBar'
  365.  
  366.      *Note Font Positions::.
  367.  
  368. 
  369. File: groff,  Node: Font Positions,  Next: Using Symbols,  Prev: Font Families,  Up: Fonts
  370.  
  371. Font Positions
  372. --------------
  373.  
  374.    For the sake of old phototypesetters and compatibility with old
  375. versions of `troff', `gtroff' has the concept of font "positions", on
  376. which various fonts are mounted.
  377.  
  378.  - Request: .fp pos font [external-name]
  379.  - Register: \n[.f]
  380.  - Register: \n[.fp]
  381.      Mount font FONT at position POS (which must be a non-negative
  382.      integer).  This numeric position can then be referred to with font
  383.      changing commands.  When `gtroff' starts it is using font
  384.      position 1 (which must exist; position 0 is unused usually at
  385.      start-up).
  386.  
  387.      The current font in use, as a font position, is available in the
  388.      read-only number register `.f'.  This can be useful to remember the
  389.      current font for later recall.  It is associated with the current
  390.      environment (*note Environments::).
  391.  
  392.  
  393.           .nr save-font \n[.f]
  394.           .ft B
  395.           ... text text text ...
  396.           .ft \n[save-font]
  397.  
  398.      The number of the next free font position is available in the
  399.      read-only number register `.fp'.  This is useful when mounting a
  400.      new font, like so:
  401.  
  402.  
  403.           .fp \n[.fp] NEATOFONT
  404.  
  405.      Fonts not listed in the `DESC' file are automatically mounted on
  406.      the next available font position when they are referenced.  If a
  407.      font is to be mounted explicitly with the `fp' request on an unused
  408.      font position, it should be mounted on the first unused font
  409.      position, which can be found in the `.fp' register.  Although
  410.      `gtroff' does not enforce this strictly, it is not allowed to
  411.      mount a font at a position whose number is much greater (approx.
  412.      1000 positions) than that of any currently used position.
  413.  
  414.      The `fp' request has an optional third argument.  This argument
  415.      gives the external name of the font, which is used for finding the
  416.      font description file.  The second argument gives the internal
  417.      name of the font which is used to refer to the font in `gtroff'
  418.      after it has been mounted.  If there is no third argument then the
  419.      internal name is used as the external name.  This feature makes it
  420.      possible to use fonts with long names in compatibility mode.
  421.  
  422.    Both the `ft' request and the `\f' escape have alternative syntax
  423. forms to access font positions.
  424.  
  425.  - Request: .ft nnn
  426.  - Escape: \fN
  427.  - Escape: \f(NN
  428.  - Escape: \f[NNN]
  429.      Change the current font position to NNN (one-digit position N,
  430.      two-digit position NN), which must be a non-negative integer.
  431.  
  432.      If NNN is associated with a style (as set with the `sty' request
  433.      or with the `styles' command in the `DESC' file), use it within
  434.      the current font family (as set with the `fam' request or with the
  435.      `family' command in the `DESC' file).
  436.  
  437.  
  438.           this is font 1
  439.           .ft 2
  440.           this is font 2
  441.           .ft                   \" switch back to font 1
  442.           .ft 3
  443.           this is font 3
  444.           .ft
  445.           this is font 1 again
  446.  
  447.      *Note Changing Fonts::, for the standard syntax form.
  448.  
  449. 
  450. File: groff,  Node: Using Symbols,  Next: Special Fonts,  Prev: Font Positions,  Up: Fonts
  451.  
  452. Using Symbols
  453. -------------
  454.  
  455.    A "glyph" is a graphical representation of a "character".  While a
  456. character is an abstract entity containing semantic information, a
  457. glyph is something which can be actually seen on screen or paper.  It
  458. is possible that a character has multiple glyph representation forms
  459. (for example, the character `A' can be either written in a roman or an
  460. italic font, yielding two different glyphs); sometimes more than one
  461. character maps to a single glyph (this is a "ligature" - the most
  462. common is `fi').
  463.  
  464.    Please note that currently the distinction between glyphs and
  465. characters in this reference is not clearly carried out.  This will be
  466. improved eventually in the next revision.
  467.  
  468.    A "symbol" is simply a named glyph.  Within `gtroff', all glyph
  469. names of a particular font are defined in its font file.  If the user
  470. requests a glyph not available in this font, `gtroff' looks up an
  471. ordered list of "special fonts".  By default, the POSTSCRIPT output
  472. device supports the two special fonts `SS' (slanted symbols) and `S'
  473. (symbols) (the former is looked up before the latter).  Other output
  474. devices use different names for special fonts.  Fonts mounted with the
  475. `fonts' keyword in the `DESC' file are globally available.  To install
  476. additional special fonts locally (i.e. for a particular font), use the
  477. `fspecial' request.
  478.  
  479.    *Note Font Files::, and *Note Special Fonts::, for more details.
  480.  
  481.  - Escape: \(NM
  482.  - Escape: \[NAME]
  483.      Insert a symbol NAME (two-character name NM).  There is no special
  484.      syntax for one-character names - the natural form `\N' would
  485.      collide with escapes.
  486.  
  487.      If NAME is undefined, a warning of type `char' is generated, and
  488.      the escape is ignored.  *Note Debugging::, for information about
  489.      warnings.
  490.  
  491.      The list of available symbols is device dependent; see *Note Glyph
  492.      Name Index:: for some of them discussed in this reference.
  493.  
  494.  
  495.  - Escape: \C'XXX'
  496.      Typeset the character named XXX.  Normally it is more convenient
  497.      to use `\[XXX]', but `\C' has the advantage that it is compatible
  498.      with newer versions of `ditroff' and is available in compatibility
  499.      mode.
  500.  
  501.  - Escape: \N'N'
  502.      Typeset the character with code N in the current font (this is
  503.      *not* the input character code).  N can be any integer.  Most
  504.      devices only have characters with codes between 0 and 255; the
  505.      Unicode output device uses codes in the range 0-65535.  If the
  506.      current font does not contain a character with that code, special
  507.      fonts are _not_ searched.  The `\N' escape sequence can be
  508.      conveniently used in conjunction with the `char' request:
  509.  
  510.  
  511.           .char \[phone] \f[ZD]\N'37'
  512.  
  513.      The code of each character is given in the fourth column in the
  514.      font description file after the `charset' command.  It is possible
  515.      to include unnamed characters in the font description file by
  516.      using a name of `---'; the `\N' escape sequence is the only way to
  517.      use these.
  518.  
  519.  - Request: .cflags n c1 c2 ...
  520.      Each character has certain properties associated with it.  These
  521.      properties can be modified with the `cflags' request.  The first
  522.      argument is the the sum of the desired flags and the remaining
  523.      arguments are the characters to have those properties.  It is
  524.      possible to omit the spaces between the characters.
  525.  
  526.     `1'
  527.           the character ends sentences (initially characters `.?!' have
  528.           this property)
  529.  
  530.     `2'
  531.           lines can be broken before the character (initially no
  532.           characters have this property)
  533.  
  534.     `4'
  535.           lines can be broken after the character (initially the
  536.           characters `-\(hy\(em' have this property)
  537.  
  538.     `8'
  539.           the character overlaps horizontally (initially the characters
  540.           `\(ul\(rn\(ru' have this property)
  541.  
  542.     `16'
  543.           the character overlaps vertically (initially character `\(br'
  544.           has this property)
  545.  
  546.     `32'
  547.           an end of sentence character followed by any number of
  548.           characters with this property is treated as the end of a
  549.           sentence if followed by a newline or two spaces; in other
  550.           words the character is "transparent" for the purposes of end
  551.           of sentence recognition - this is the same as having a zero
  552.           space factor in TeX (initially characters `"')]*\(dg\(rq'
  553.           have this property).
  554.  
  555.  - Request: .char c [string]
  556.      Define a new character C to be STRING (which can be empty).  Every
  557.      time character C needs to be printed, STRING is processed in a
  558.      temporary environment and the result is wrapped up into a single
  559.      object.  Compatibility mode is turned off and the escape character
  560.      is set to `\' while STRING is being processed.  Any emboldening,
  561.      constant spacing or track kerning is applied to this object rather
  562.      than to individual characters in STRING.  A character defined by
  563.      this request can be used just like a normal character provided by
  564.      the output device.  In particular, other characters can be
  565.      translated to it with the `tr' request; it can be made the leader
  566.      character by the `lc' request; repeated patterns can be drawn with
  567.      the character using the `\l' and `\L' escape sequences; words
  568.      containing the character can be hyphenated correctly, if the
  569.      `hcode' request is used to give the character a hyphenation code.
  570.      There is a special anti-recursion feature: Use of character within
  571.      the character's definition is handled like normal characters not
  572.      defined with `char'.
  573.  
  574.  - Request: .rchar c1 c2 ...
  575.      Remove the definitions of characters C1, C2, .... This undoes the
  576.      effect of a `char' request.
  577.  
  578.      It is possible to omit the whitespace between arguments.
  579.  
  580.    *Note Special Characters::.
  581.  
  582. 
  583. File: groff,  Node: Special Fonts,  Next: Artificial Fonts,  Prev: Using Symbols,  Up: Fonts
  584.  
  585. Special Fonts
  586. -------------
  587.  
  588.    To be written.
  589.  
  590. 
  591. File: groff,  Node: Artificial Fonts,  Next: Ligatures and Kerning,  Prev: Special Fonts,  Up: Fonts
  592.  
  593. Artificial Fonts
  594. ----------------
  595.  
  596.    There are a number of requests for artificially creating fonts.
  597. These are largely vestiges of the days when output devices did not have
  598. a wide variety of fonts, and when `nroff' and `troff' were separate
  599. programs.  These are no longer necessary in GNU `troff'.  Nevertheless,
  600. they are supported.
  601.  
  602.  - Request: .ul [lines]
  603.      The `ul' request normally underlines subsequent lines if a tty
  604.      output device is used.  Otherwise, the lines are printed in italics
  605.      (only the term `underlined' is used in the following).  The single
  606.      argument is the number of input lines to be underlined; with no
  607.      argument, the next line is underlined.  If LINES is zero or
  608.      negative, stop the effects of `ul' (if it was active).  Requests
  609.      and empty lines do not count for computing the number of underlined
  610.      input lines, even if they produce some output like `tl'.  Lines
  611.      inserted by macros (e.g. invoked by a trap) do count.
  612.  
  613.      At the beginning of `ul', the current font is stored and the
  614.      underline font is activated.  Within the span of a `ul' request,
  615.      it is possible to change fonts, but after the last line affected by
  616.      `ul' the saved font is restored.
  617.  
  618.      This command is associated with the current environment.  The
  619.      underline font can be changed with the `uf' request.
  620.  
  621.      *Note Troff and Nroff Mode::, for a discussion how underlining is
  622.      implemented in for tty output devices, and which problems can
  623.      arise.
  624.  
  625.      The `ul' request does not underline spaces.
  626.  
  627.  - Request: .cu [lines]
  628.      The `cu' request is similar to `ul' but underlines spaces as well
  629.      (if a tty output device is used).
  630.  
  631.  - Request: .uf font
  632.      Set the underline font (globally) used by `ul' and `cu'.  By
  633.      default, this is the font at position 2.  FONT can be either a
  634.      non-negative font position or the name of a font.
  635.  
  636.  - Request: .bd font [offset]
  637.  - Request: .bd font1 font2 [offset]
  638.  - Register: \n[.b]
  639.      Artificially create a bold font by printing each character twice,
  640.      slightly offset.
  641.  
  642.      Two syntax forms are available.
  643.  
  644.         * Imitate a bold font unconditionally.  The first argument
  645.           specifies the font to embolden, and the second is the number
  646.           of basic units, minus one, by which the two characters is
  647.           offset.  If the second argument is missing, emboldening is
  648.           turned off.
  649.  
  650.           FONT can be either a non-negative font position or the name
  651.           of a font.
  652.  
  653.           OFFSET is available in the `.b' read-only register if a
  654.           special font is active; in the `bd' request, its default unit
  655.           is `u'.
  656.  
  657.         * Imitate a bold form conditionally.  Embolden FONT1 by OFFSET
  658.           only if font FONT2 is the current font.  This command can be
  659.           issued repeatedly to set up different emboldening values for
  660.           different current fonts.  If the second argument is missing,
  661.           emboldening is turned off for this particular current font.
  662.  
  663.           This affects special fonts only (either set up with the
  664.           `special' command in font files or with the `fspecial'
  665.           request).
  666.  
  667.  - Request: .cs font [width [em-size]]
  668.      Switch to and from constant character space mode.  If activated,
  669.      the width of every character is WIDTH/36 ems.  The em size is
  670.      given absolutely by EM-SIZE; if this argument is missing, the em
  671.      value is taken from the current font size (as set with the `ps'
  672.      request) when the font is effectively in use.  Without second and
  673.      third argument, constant character space mode is deactivated.
  674.  
  675.      Default unit for EM-SIZE is `z'; WIDTH is an integer.
  676.  
  677. 
  678. File: groff,  Node: Ligatures and Kerning,  Prev: Artificial Fonts,  Up: Fonts
  679.  
  680. Ligatures and Kerning
  681. ---------------------
  682.  
  683.    Ligatures are groups of characters that are run together.  For
  684. example, the letters `f' and `i' can form a ligature `fi' as in the
  685. word `file'.  This produces a cleaner look (albeit subtle) to the
  686. printed output.  Usually, ligatures are not available in fonts for tty
  687. output devices.
  688.  
  689.    Most POSTSCRIPT fonts support the fi and fl ligatures.  The C/A/T
  690. typesetter that was the target of AT&T `troff' also supported `ff',
  691. `ffi', and `ffl' ligatures.  Advanced typesetters or `expert' fonts may
  692. include ligatures for `ft' and `ct', although GNU `troff' does not
  693. support these (yet).
  694.  
  695.  - Request: .lg [flag]
  696.  - Register: \n[.lg]
  697.      The ligature mechanism can be switched on or off with the `lg'
  698.      request; if the parameter is non-zero or missing, ligatures are
  699.      enabled, otherwise disabled.  Default is on.  The current ligature
  700.      mode can be found in the read-only number register `.lg' (set to 1
  701.      or 2 if ligatures are enabled, 0 otherwise).
  702.  
  703.      Setting the ligature mode to 2 enables the two-character ligatures
  704.      (fi, fl, and ff) and disables the three-character ligatures (ffi
  705.      and ffl).
  706.  
  707.    "Pairwise kerning" is another subtle typesetting mechanism that
  708. modifies the distance between a character pair to improve readability.
  709. In most cases (but not always) the distance is decreased.
  710. Typewriter-like fonts and fonts for terminals where all characters have
  711. the same width don't use kerning.
  712.  
  713.  - Request: .kern [flag]
  714.  - Register: \n[.kern]
  715.      Kerning can be activated with the `kern' request.  If the
  716.      parameter is non-zero or missing, enable pairwise kerning,
  717.      otherwise disable it.  The read-only number register `.kern' is
  718.      set to 1 if pairwise kerning is enabled, 0 otherwise.
  719.  
  720.      If the font description file contains pairwise kerning information,
  721.      characters from that font are kerned.  Kerning between two
  722.      characters can be inhibited by placing `\&' between them: `V\&A'.
  723.  
  724.      *Note Font File Format::.
  725.  
  726.    "Track kerning" expands or reduces the space between characters.
  727. This can be handy, for example, if you need to squeeze a long word onto
  728. a single line or spread some text to fill a narrow column.  It must be
  729. used with great care since it is usually considered bad typography if
  730. the reader notices the effect.
  731.  
  732.  - Request: .tkf f s1 n1 s2 n2
  733.      Enable track kerning for font F.  If the current font is F the
  734.      width of every character is increased by an amount between N1 and
  735.      N2 (N1, N2 can be negative); if the current point size is less
  736.      than or equal to S1 the width is increased by N1; if it is greater
  737.      than or equal to S2 the width is increased by N2; if the point
  738.      size is greater than or equal to S1 and less than or equal to S2
  739.      the increase in width is a linear function of the point size.
  740.  
  741.      The default unit is `z' for S1 and S2, `p' for N1 and N2.
  742.  
  743.    Sometimes, when typesetting letters of different fonts, more or less
  744. space at such boundaries are needed.  There are two escapes to help
  745. with this.
  746.  
  747.  - Escape: \/
  748.      Increase the width of the preceding character so that the spacing
  749.      between that character and the following character is correct if
  750.      the following character is a roman character.  For example, if an
  751.      italic `f' is immediately followed by a roman right parenthesis,
  752.      then in many fonts the top right portion of the `f' overlaps the
  753.      top left of the right parenthesis.  Use this escape sequence
  754.      whenever an italic character is immediately followed by a roman
  755.      character without any intervening space.  This small amount of
  756.      space is also called "italic correction".
  757.  
  758.  
  759.  - Escape: \,
  760.      Modify the spacing of the following character so that the spacing
  761.      between that character and the preceding character is correct if
  762.      the preceding character is a roman character.  Use this escape
  763.      sequence whenever a roman character is immediately followed by an
  764.      italic character without any intervening space.  In analogy to
  765.      above, this space could be called "left italic correction", but
  766.      this term isn't used widely.
  767.  
  768.  
  769.  - Escape: \&
  770.      Insert a zero-width character, which is invisible.  Its intended
  771.      use is to stop interaction of a character with its surrounding.
  772.  
  773.         * It prevents the insertion of extra space after an end of
  774.           sentence character.
  775.  
  776.  
  777.                Test.
  778.                Test.
  779.                    => Test.  Test.
  780.                Test.\&
  781.                Test.
  782.                    => Test. Test.
  783.  
  784.         * It prevents interpretation of a control character at the
  785.           beginning of an input line.
  786.  
  787.  
  788.                .Test
  789.                    => warning: `Test' not defined
  790.                \&.Test
  791.                    => .Test
  792.  
  793.         * It prevents kerning between two characters.
  794.  
  795.         * It is needed to map an arbitrary character to nothing in the
  796.           `tr' request (*note Character Translations::).
  797.  
  798. 
  799. File: groff,  Node: Sizes,  Next: Strings,  Prev: Fonts,  Up: gtroff Reference
  800.  
  801. Sizes
  802. =====
  803.  
  804.    `gtroff' uses two dimensions with each line of text, type size and
  805. vertical spacing.  The "type size" is approximately the height of the
  806. tallest character.(1) (*note Sizes-Footnote-1::)  "Vertical spacing" is
  807. the amount of space `gtroff' allows for a line of text; normally, this
  808. is about 20% larger than the current type size.  Ratios smaller than
  809. this can result in hard-to-read text; larger than this, it spreads the
  810. text out more vertically (useful for term papers).  By default,
  811. `gtroff' uses 10 point type on 12 point spacing.
  812.  
  813.    The difference between type size and vertical spacing is known, by
  814. typesetters, as "leading".
  815.  
  816. * Menu:
  817.  
  818. * Changing Type Sizes::
  819. * Fractional Type Sizes::
  820.  
  821. 
  822. File: groff,  Node: Sizes-Footnotes,  Up: Sizes
  823.  
  824.    (1) This is usually the parenthesis.  Note that in most cases the
  825. real dimensions of the glyphs in a font are _not_ related to its type
  826. size!  For example, the standard POSTSCRIPT font families `Times
  827. Roman', `Helvetica', and `Courier' can't be used together at 10pt; to
  828. get acceptable output, the size of `Helvetica' has to be reduced by one
  829. point, and the size of `Courier' must be increased by one point.
  830.  
  831. 
  832. File: groff,  Node: Changing Type Sizes,  Next: Fractional Type Sizes,  Prev: Sizes,  Up: Sizes
  833.  
  834. Changing Type Sizes
  835. -------------------
  836.  
  837.  - Request: .ps [size]
  838.  - Request: .ps +size
  839.  - Request: .ps -size
  840.  - Escape: \sSIZE
  841.  - Register: \n[.s]
  842.      Use the `ps' request or the `\s' escape to change (increase,
  843.      decrease) the type size (in points).  Specify SIZE as either an
  844.      absolute point size, or as a relative change from the current size.
  845.      The size 0, or no argument, goes back to the previous size.
  846.  
  847.      Default unit of `size' is `z'.  If `size' is zero or negative, it
  848.      is set to 1u.
  849.  
  850.      The read-only number register `.s' returns the point size in
  851.      points as a decimal fraction.  This is a string.  To get the point
  852.      size in scaled points, use the `.ps' register instead.
  853.  
  854.      `.s' is associated with the current environment (*note
  855.      Environments::).
  856.  
  857.  
  858.           snap, snap,
  859.           .ps +2
  860.           grin, grin,
  861.           .ps +2
  862.           wink, wink, \s+2nudge, nudge,\s+8 say no more!
  863.           .ps 10
  864.  
  865.      The `\s' escape may be called in a variety of ways.  Much like
  866.      other escapes there must be a way to determine where the argument
  867.      ends and the text begins.  Any of the following forms are valid:
  868.  
  869.     `\sN'
  870.           Set the point size to N points.  N must be either 0 or in the
  871.           range 4 to 39.
  872.  
  873.     `\s+N'
  874.     `\s-N'
  875.           Increase or decrease the point size by N points.  N must be
  876.           exactly one digit.
  877.  
  878.     `\s(NN'
  879.           Set the point size to NN points.  NN must be exactly two
  880.           digits.
  881.  
  882.     `\s+(NN'
  883.     `\s-(NN'
  884.     `\s(+NN'
  885.     `\s(-NN'
  886.           Increase or decrease the point size by NN points.  NN must be
  887.           exactly two digits.
  888.  
  889.      *Note Fractional Type Sizes::, for yet another syntactical form of
  890.      using the `\s' escape.
  891.  
  892.      Some devices may only have certain permissible sizes, in which case
  893.      `gtroff' rounds to the nearest permissible size.
  894.  
  895.  - Request: .vs [space]
  896.  - Request: .vs +space
  897.  - Request: .vs -space
  898.  - Register: \n[.v]
  899.      Change (increase, decrease) the vertical spacing by SPACE.  The
  900.      default unit is `p'.
  901.  
  902.      If `vs' is called without an argument, the vertical spacing is
  903.      reset to the previous value before the last call to `vs'.
  904.  
  905.      `gtroff' creates a warning of type `range' if SPACE is zero or
  906.      negative; the vertical spacing is then set to the vertical
  907.      resolution (as given in the `.V' register).
  908.  
  909.      The read-only number register `.v' contains the current vertical
  910.      spacing; it is associated with the current environment (*note
  911.      Environments::).
  912.  
  913. 
  914. File: groff,  Node: Fractional Type Sizes,  Prev: Changing Type Sizes,  Up: Sizes
  915.  
  916. Fractional Type Sizes
  917. ---------------------
  918.  
  919.    A "scaled point" is equal to 1/SIZESCALE points, where SIZESCALE is
  920. specified in the `DESC' file (1 by default).  There is a new scale
  921. indicator `z' which has the effect of multiplying by SIZESCALE.
  922. Requests and escape sequences in `gtroff' interpret arguments that
  923. represent a point size as being in units of scaled points, but they
  924. evaluate each such argument using a default scale indicator of `z'.
  925. Arguments treated in this way are the argument to the `ps' request, the
  926. third argument to the `cs' request, the second and fourth arguments to
  927. the `tkf' request, the argument to the `\H' escape sequence, and those
  928. variants of the `\s' escape sequence that take a numeric expression as
  929. their argument (see below).
  930.  
  931.    For example, suppose SIZESCALE is 1000; then a scaled point is
  932. equivalent to a millipoint; the request `.ps 10.25' is equivalent to
  933. `.ps 10.25z' and thus sets the point size to 10250 scaled points, which
  934. is equal to 10.25 points.
  935.  
  936.    `gtroff' disallows the use of the `z' scale indicator in instances
  937. where it would make no sense, such as a numeric expression whose
  938. default scale indicator was neither `u' nor `z'.  Similarly it would
  939. make no sense to use a scaling indicator other than `z' or `u' in a
  940. numeric expression whose default scale indicator was `z', and so
  941. `gtroff' disallows this as well.
  942.  
  943.    There is also new scale indicator `s' which multiplies by the number
  944. of units in a scaled point.  So, for example, `\n[.ps]s' is equal to
  945. `1m'.  Be sure not to confuse the `s' and `z' scale indicators.
  946.  
  947.  - Register: \n[.ps]
  948.      A read-only number register returning the point size in scaled
  949.      points.
  950.  
  951.      `.ps' is associated with the current environment (*note
  952.      Environments::).
  953.  
  954.  - Register: \n[.psr]
  955.  - Register: \n[.sr]
  956.      The last-requested point size in scaled points is contained in the
  957.      `.psr' read-only number register.  The last requested point size
  958.      in points as a decimal fraction can be found in `.sr'.  This is a
  959.      string-valued read-only number register.
  960.  
  961.      Note that the requested point sizes are device-independent, whereas
  962.      the values returned by the `.ps' and `.s' registers are not.  For
  963.      example, if a point size of 11pt is requested for a DVI device,
  964.      10.95pt are actually used (as specified in the `DESC' file).
  965.  
  966.      Both registers are associated with the current environment (*note
  967.      Environments::).
  968.  
  969.    The `\s' escape has the following syntax for working with fractional
  970. type sizes:
  971.  
  972. `\s[N]'
  973. `\s'N''
  974.      Set the point size to N scaled points; N is a numeric expression
  975.      with a default scale indicator of `z'.
  976.  
  977. `\s[+N]'
  978. `\s[-N]'
  979. `\s+[N]'
  980. `\s-[N]'
  981. `\s'+N''
  982. `\s'-N''
  983. `\s+'N''
  984. `\s-'N''
  985.      Increase or or decrease the point size by N scaled points; N is a
  986.      numeric expression with a default scale indicator of `z'.
  987.  
  988.    *Note Font Files::.
  989.  
  990. 
  991. File: groff,  Node: Strings,  Next: Conditionals and Loops,  Prev: Sizes,  Up: gtroff Reference
  992.  
  993. Strings
  994. =======
  995.  
  996.    `gtroff' has string variables, which are entirely for user
  997. convenience (i.e. there are no built-in strings exept `.T', but even
  998. this is a read-write string variable).
  999.  
  1000.  - Request: .ds name [string]
  1001.  - Escape: \*N
  1002.  - Escape: \*(NM
  1003.  - Escape: \*[NAME]
  1004.      Define and access a string variable NAME (one-character name N,
  1005.      two-character name NM).  If NAME already exists, `ds' overwrites
  1006.      the previous definition.
  1007.  
  1008.      Example:
  1009.  
  1010.  
  1011.           .ds UX \s-1UNIX\s0\u\s-3tm\s0\d
  1012.           .
  1013.           The \*(UX Operating System
  1014.  
  1015.      The `\*' escape "interpolates" (expands in-place) a
  1016.      previously-defined string variable.  To be more precise, the stored
  1017.      string is pushed onto the input stack which is then parsed by
  1018.      `gtroff'.  Similar to number registers, it is possible to nest
  1019.      strings, i.e. a string variables can be called within string
  1020.      variables.
  1021.  
  1022.      If the string named by the `\*' does not exist, it is defined as
  1023.      empty, and a warning of type `mac' is emitted (see *Note
  1024.      Debugging::, for more details).
  1025.  
  1026.      *Caution:* Unlike other requests, the second argument to the `ds'
  1027.      request takes up the entire line including trailing spaces.  This
  1028.      means that comments on a line with such a request can introduce
  1029.      unwanted space into a string.
  1030.  
  1031.  
  1032.           .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
  1033.  
  1034.      Instead the comment should be put on another line or have the
  1035.      comment escape adjacent with the end of the string.
  1036.  
  1037.  
  1038.           .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\"  UNIX trademark
  1039.  
  1040.      To produce leading space the string can be started with a double
  1041.      quote.  No trailing quote is needed; in fact, any trailing quote is
  1042.      included in your string.
  1043.  
  1044.  
  1045.           .ds sign "           Yours in a white wine sauce,
  1046.  
  1047.      Strings are not limited to a single line of text.  A string can
  1048.      span several lines by escaping the newlines with a backslash.  The
  1049.      resulting string is stored _without_ the newlines.
  1050.  
  1051.  
  1052.           .ds foo lots and lots \
  1053.           of text are on these \
  1054.           next several lines
  1055.  
  1056.      It is not possible to have real newlines in a string.
  1057.  
  1058.      Strings, macros, and diversions (and boxes) share the same name
  1059.      space.  Internally, even the same mechanism is used to store them.
  1060.      This has some interesting consequences.  For example, it is
  1061.      possible to call a macro with string syntax and vice versa.
  1062.  
  1063.  
  1064.           .de xxx
  1065.           a funny test.
  1066.           ..
  1067.           This is \*[xxx]
  1068.               => This is a funny test.
  1069.           
  1070.           .ds yyy a funny test
  1071.           This is
  1072.           .yyy
  1073.               => This is a funny test.
  1074.  
  1075.      Diversions and boxes can be also called with string syntax.  It is
  1076.      not possible to pass arguments to a macro if called with `\*'.
  1077.  
  1078.      Another consequence is that you can copy one-line diversions or
  1079.      boxes to a string.
  1080.  
  1081.  
  1082.           .di xxx
  1083.           a \fItest\fR
  1084.           .br
  1085.           .di
  1086.           .ds yyy This is \*[xxx]\c
  1087.           \*[yyy].
  1088.               => This is a test.
  1089.  
  1090.      As the previous example shows, it is possible to store formatted
  1091.      output in strings.  The `\c' escape prevents the insertion of an
  1092.      additional blank line in the output.
  1093.  
  1094.      Copying diversions longer than a single output line produces
  1095.      unexpected results.
  1096.  
  1097.  
  1098.           .di xxx
  1099.           a funny
  1100.           .br
  1101.           test
  1102.           .br
  1103.           .di
  1104.           .ds yyy This is \*[xxx]\c
  1105.           \*[yyy].
  1106.               => test This is a funny.
  1107.  
  1108.      Usually, it is not predictable whether a diversion contains one or
  1109.      more output lines, so this mechanism should be avoided.  With UNIX
  1110.      `troff', this was the only solution to strip off a final newline
  1111.      from a diversion.  Another disadvantage is that the spaces in the
  1112.      copied string are already formatted, making them unstretchable.
  1113.      This can cause ugly results.
  1114.  
  1115.      A clean solution to this problem is available in GNU `troff',
  1116.      using the requests `chop' to remove the final newline of a
  1117.      diversion, and `unformat' to make the horizontal spaces
  1118.      stretchable again.
  1119.  
  1120.  
  1121.           .box xxx
  1122.           a funny
  1123.           .br
  1124.           test
  1125.           .br
  1126.           .box
  1127.           .chop xxx
  1128.           .unformat xxx
  1129.           This is \*[xxx].
  1130.               => This is a funny test.
  1131.  
  1132.      *Note Gtroff Internals::, for more information.
  1133.  
  1134.  - Request: .as name [string]
  1135.      The `as' request is similar to `ds' but appends STRING to the
  1136.      string stored as NAME instead of redefining it.  If NAME doesn't
  1137.      exist yet, it is created.
  1138.  
  1139.  
  1140.           .as sign " with shallots, onions and garlic,
  1141.  
  1142.  
  1143.    Rudimentary string manipulation routines are given with the next two
  1144. requests.
  1145.  
  1146.  - Request: .substring str n1 [n2]
  1147.      Replace the string in register STR with the substring defined by
  1148.      the indices N1 and N2.  The first character in the string has
  1149.      index one.  If N2 is omitted, it is taken to be equal to the
  1150.      string's length.  If the index value N1 or N2 is negative or zero,
  1151.      it is counted from the end of the string, going backwards: The
  1152.      last character has index 0, the character before the last
  1153.      character has index -1, etc.
  1154.  
  1155.  
  1156.           .ds xxx abcdefgh
  1157.           .substring xxx 2 -3
  1158.           \*[xxx]
  1159.               => bcde
  1160.  
  1161.  
  1162.  - Request: .length reg str
  1163.      Compute the length of STR and returns it in the number
  1164.      register REG.  If REG doesn't exist, it is created.
  1165.  
  1166.  
  1167.           .ds xxx abcdefgh
  1168.           .length yyy xxx
  1169.           \n[yyy]
  1170.               => 8
  1171.  
  1172.  
  1173.  - Request: .rn xx yy
  1174.      Rename the request, macro, or string XX to YY.
  1175.  
  1176.  - Request: .rm xx
  1177.      Remove the request, macro, or string XX.  `gtroff' treats
  1178.      subsequent invocations as if the object had never been defined.
  1179.  
  1180.  - Request: .als new old
  1181.      Create an alias named NEW for the request, string, macro, or
  1182.      diversion object named OLD.  The new name and the old name are
  1183.      exactly equivalent (it is similar to a hard rather than a soft
  1184.      link). If OLD is undefined, `gtroff' generates a warning of type
  1185.      `mac' and ignores the request.
  1186.  
  1187.  - Request: .chop xx
  1188.      Remove (chop) the last character from the macro, string, or
  1189.      diversion named XX. This is useful for removing the newline from
  1190.      the end of diversions that are to be interpolated as strings.
  1191.      This command can be used repeatedly; see *Note Gtroff Internals::,
  1192.      for details on nodes inserted by `gtroff' automatically.
  1193.  
  1194.    *Note Identifiers::, and *Note Comments::.
  1195.  
  1196. 
  1197. File: groff,  Node: Conditionals and Loops,  Next: Writing Macros,  Prev: Strings,  Up: gtroff Reference
  1198.  
  1199. Conditionals and Loops
  1200. ======================
  1201.  
  1202. * Menu:
  1203.  
  1204. * Operators in Conditionals::
  1205. * if-else::
  1206. * while::
  1207.  
  1208. 
  1209. File: groff,  Node: Operators in Conditionals,  Next: if-else,  Prev: Conditionals and Loops,  Up: Conditionals and Loops
  1210.  
  1211. Operators in Conditionals
  1212. -------------------------
  1213.  
  1214.    In `if' and `while' requests, there are several more operators
  1215. available:
  1216.  
  1217. `e'
  1218. `o'
  1219.      True if the current page is even or odd numbered (respectively).
  1220.  
  1221. `n'
  1222.      True if the document is being processed in nroff mode (i.e., the
  1223.      `.nroff' command has been issued).
  1224.  
  1225. `t'
  1226.      True if the document is being processed in troff mode (i.e., the
  1227.      `.troff' command has been issued).
  1228.  
  1229. `v'
  1230.      Always false.
  1231.  
  1232. `'XXX'YYY''
  1233.      True if the string XXX is equal to the string YYY.  Other
  1234.      characters can be used in place of the single quotes; the same set
  1235.      of delimiters as for the `\D' escape is used (*note Escapes::).
  1236.      `gtroff' formats the strings before being compared:
  1237.  
  1238.  
  1239.           .ie "|"\fR|\fP" \
  1240.           true
  1241.           .el \
  1242.           false
  1243.               => true
  1244.  
  1245.      The resulting motions, character sizes, and fonts have to
  1246.      match,(1) (*note Operators in Conditionals-Footnote-1::) and not
  1247.      the individual motion, size, and font requests.  In the previous
  1248.      example, `|' and `\fR|\fP' both result in a roman `|' character
  1249.      with the same point size and at the same location on the page, so
  1250.      the strings are equal.  If `.ft I' had been added before the
  1251.      `.ie', the result would be "false" because (the first) `|'
  1252.      produces an italic `|' rather than a roman one.
  1253.  
  1254. `r XXX'
  1255.      True if there is a number register named XXX.
  1256.  
  1257. `d XXX'
  1258.      True if there is a string, macro, diversion, or request named XXX.
  1259.  
  1260. `c CH'
  1261.      True if there is a character CH available; CH is either an ASCII
  1262.      character or a special character (`\(CH' or `\[CH]'); the
  1263.      condition is also true if CH has been defined by the `char'
  1264.      request.
  1265.  
  1266.    Note that these operators can't be combined with other operators like
  1267. `:' or `&'; only a leading `!' (without whitespace between the
  1268. exclamation mark and the operator) can be used to negate the result.
  1269.  
  1270.  
  1271.      .nr xxx 1
  1272.      .ie !r xxx \
  1273.      true
  1274.      .el \
  1275.      false
  1276.          => false
  1277.  
  1278.    A whitespace after `!' always evaluates to zero (this bizarre
  1279. behaviour is due to compatibility with UNIX `troff').
  1280.  
  1281.  
  1282.      .nr xxx 1
  1283.      .ie ! r xxx \
  1284.      true
  1285.      .el \
  1286.      false
  1287.          => r xxx true
  1288.  
  1289.    It is possible to omit the whitespace before the argument to the
  1290. `r', `d', and `c' operators.
  1291.  
  1292.    *Note Expressions::.
  1293.  
  1294. 
  1295. File: groff,  Node: Operators in Conditionals-Footnotes,  Up: Operators in Conditionals
  1296.  
  1297.    (1) The created output nodes must be identical.  *Note Gtroff
  1298. Internals::.
  1299.  
  1300. 
  1301. File: groff,  Node: if-else,  Next: while,  Prev: Operators in Conditionals,  Up: Conditionals and Loops
  1302.  
  1303. if-else
  1304. -------
  1305.  
  1306.    `gtroff' has if-then-else constructs like other languages, although
  1307. the formatting can be painful.
  1308.  
  1309.  - Request: .if expr anything
  1310.      Evaluate the expression EXPR, and executes ANYTHING (the remainder
  1311.      of the line) if EXPR evaluates to non-zero (true).  ANYTHING is
  1312.      interpreted as though it was on a line by itself (except that
  1313.      leading spaces are swallowed).  *Note Expressions::, for more info.
  1314.  
  1315.  
  1316.           .nr xxx 1
  1317.           .nr yyy 2
  1318.           .if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
  1319.               => true
  1320.  
  1321.  
  1322.  - Request: .ie expr anything
  1323.  - Request: .el anything
  1324.      Use the `ie' and `el' requests to write an if-then-else.  The
  1325.      first request is the `if' part and the latter is the `else' part.
  1326.  
  1327.  
  1328.           .ie n .ls 2 \" double spacing in nroff
  1329.           .el   .ls 1 \" single spacing in troff
  1330.  
  1331.  
  1332.    In many cases, an if (or if-else) construct needs to execute more
  1333. than one request.  This can be done using the `\{' and `\}' escapes.
  1334. The following example shows the possible ways to use these escapes
  1335. (note the position of the opening and closing braces).
  1336.  
  1337.  
  1338.      .ie t \{\
  1339.      .    ds lq ``
  1340.      .    ds rq ''
  1341.      .\}
  1342.      .el \
  1343.      .\{\
  1344.      .    ds lq "
  1345.      .    ds rq "\}
  1346.  
  1347.    *Note Expressions::.
  1348.  
  1349. 
  1350. File: groff,  Node: while,  Prev: if-else,  Up: Conditionals and Loops
  1351.  
  1352. while
  1353. -----
  1354.  
  1355.    `gtroff' provides a looping construct using the `while' request,
  1356. which is used much like the `if' (and related) requests.
  1357.  
  1358.  - Request: .while expr anything
  1359.      Evaluate the expression EXPR, and repeatedly execute ANYTHING (the
  1360.      remainder of the line) until EXPR evaluates to 0.
  1361.  
  1362.  
  1363.           .nr a 0 1
  1364.           .while (\na < 9) \{\
  1365.           \n+a,
  1366.           .\}
  1367.           \n+a
  1368.               => 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
  1369.  
  1370.      Some remarks.
  1371.  
  1372.         * The body of a `while' request is treated like the body of a
  1373.           `de' request: `gtroff' temporarily stores it in a macro which
  1374.           is deleted after the loop has been exited.  It can
  1375.           considerably slow down a macro if the body of the `while'
  1376.           request (within the macro) is large.  Each time the macro is
  1377.           executed, the `while' body is parsed and stored again as a
  1378.           temporary macro.
  1379.  
  1380.  
  1381.                .de xxx
  1382.                .  nr num 10
  1383.                .  while (\\n[num] > 0) \{\
  1384.                .    \" many lines of code
  1385.                .    nr num -1
  1386.                .  \}
  1387.                ..
  1388.  
  1389.           The traditional and ofter better solution (UNIX `troff'
  1390.           doesn't have the `while' request) is to use a recursive macro
  1391.           instead which is parsed only once during its definition.
  1392.  
  1393.  
  1394.                .de yyy
  1395.                .  if (\\n[num] > 0) \{\
  1396.                .    \" many lines of code
  1397.                .    nr num -1
  1398.                .    yyy
  1399.                .  \}
  1400.                ..
  1401.                .
  1402.                .de xxx
  1403.                .  nr num 10
  1404.                .  yyy
  1405.                ..
  1406.  
  1407.           Note that the number of available recursion levels is set
  1408.           to 1000 (this is a compile-time constant value of `gtroff').
  1409.  
  1410.         * The closing brace of a `while' body must end a line.
  1411.  
  1412.  
  1413.                .if 1 \{\
  1414.                .  nr a 0 1
  1415.                .  while (\n[a] < 10) \{\
  1416.                .    nop \n+[a]
  1417.                .\}\}
  1418.                    => unbalanced \{ \}
  1419.  
  1420.  
  1421.  - Request: .break
  1422.      Break out of a `while' loop.  Be sure not to confuse this with the
  1423.      `br' request (causing a line break).
  1424.  
  1425.  - Request: .continue
  1426.      Finishes the current iteration of a `while' loop, immediately
  1427.      restarting the next iteration.
  1428.  
  1429.    *Note Expressions::.
  1430.  
  1431.